Wail Basic Documentation
by Charles Lechasseur


What is this?

This file is meant to be a quick guide to Wail. It tries to explain all the features of Wail as clearly as possible, starting from the most basic ones and going deep into the complex features later on. If you have a question about the interface or a particular feature, come here first before e-mailing me. If you still don't understand how it works after reading this, please write me so I can explain it in a later release.

If you think something is not clear and have a better way of saying it, please don't hesitate to suggest it. It will only make this document better. Any contribution will be acknowledged in the ReadMe and in this document, of course.

Hopefully, I can get Balloon Help support back in Wail as SE had pretty good Balloon Helps. This is all a matter of time, and I don't want to make any promises yet.


A little note about the terms used

Here is a list of the most common terms used in this document.

Sound variation: in Marathon, each sound can have up to 5 different variations. This means that when the engine plays the sound, it randomly picks one to play. This is the reason why Loons don't always sound the same, or why some enemies shriek differently each time you wake them up. (Note: if "More Sounds" is disabled in the Marathon prefs, the engine will load and play the first variation from each class only.)

Class: a class contains all the info about a particular sound, including the sound flags, its 5 variations (or less, 5 is the maximum number), its ID (a unique number used by the engine to load sounds), etc.

Class ID: the Marathon engine refers to sound classes by their ID. each class must have a unique ID if you want it to work with the engine. Also, the IDs must be in the range of 8192 to 32767, and must be divisible by 5 (except for totally empty classes which should have an ID of -1, which is the only non-unique ID possible - it tells the engine to ignore the class).

Flags: a flag is like a setting or a preference for a particular class. It tells the engine about how it should treat or play a particular sound. This could mean to not have the sound blocked by media, or to treat the sound as an Ambient sound, etc.

Volume: a sound's volume is NOT related to how loud it will play in Marathon - more to how far is it heard. a Loud sound will be heard from farther in a level (more polygons). Note that the last setting, Volume 3, is only available in the game ZPC, it seems.

Shuttle: a shuttle is a self-running patcher that allows you to install sounds into a Marathon sound file. Creating a shuttle allows you to distribute custom-made sounds across the internet without having to include the full sound file (which would also be illegal if it contains Bungie-made sounds). pretty useful for scenario makers.

Virtual Memory: Wail uses a custom-made Virtual Memory system that works a little bit like the MacOS Virtual Memory (albeit much more inefficiently). When Wail runs out of memory to store sounds, it writes them to disk. If you're tight in RAM, you can probably safely reduce the Wail memory allocation in the Finder and use disk-based memory instead. (never go below the minimum however, as Wail would most probably crash.)


Creating and opening files

Opening a sound file is as easy as selecting Open from the File menu and choosing your file. Currently, you can only open files whose file type is 'snd2' (Marathon 2) and 'snd' (Marathon Infinity). Any other types of sound file can still be opened but you'll have to manually change the file types in order to open them. (You can use ResEdit to do this, or FileBuddy.)

After choosing the file and selecting Open, a small progress dialog will show up for some time while Wail loads the content of the sound file (only the class information is loaded in RAM - the existing sounds are kept on disk and read from there). A sound editing window should then open up.

Wail can also create completely new, blank sound files (something SE could not). Selecting New from the file menu will create a blank sound file, with no classes. You can then Add classes to it (see a little further down) to work with it.


The sound window

The sound window is the heart of all Wail editing. It sports a redesigned interface, compared to the old SE one, which is more MacOS-like and more practical. Here is a picture of the window.






































I will explain here in details all the numbered parts and how to use them.

1. Class list
A list of all sound classes in the file. They are all named according to a Class Names file which is loaded at startup time (more on this later). Select a class in the list to view its sounds.

2. Sound lists
In Wail, the 8-bit and 16-bit sounds in a file are displayed contiguously for easier browsing. Each sound is represented by its size in bytes. You can select a sound in one of the two lists to manipulate it. Double-clicking on a sound will play it. You can also issue sound-related commands (see below).

3. Flags
The flags for this class. They control various behaviors of the class when used by the Marathon engine. Here is an explanation of each flag (this is taken from the SE readme):

- Cannot be restarted: The sound cannot play over and over, like an ambient sound. It'll play once and then shut up.
- Doesn't self-abort: This flag was dug up from Anvil's backup sound window. I have no idea what it does at this time - maybe (just maybe) it prevents a sound from stopping by itself (i.e. when the sound is done playing) and forces the sound to loop. I don't know if this flag is used at all in the original game.
- Resists pitch changes: I am still unsure what this flag does, but it does exist. It is probably pretty similar to the "Can't change pitch" flag.
- Can't change pitch: Pretty obvious. Various things could cause a sound to change pitch in the game: hearing it in a media, assigning it to a Tiny creature, etc.
- Can't be obstructed: This sound cannot be obstructed by walls, etc. Actually i don't really know if it has an effect in the game.
- Can't be media obstructed: This sound travels through media. Again, i have no idea if this is ever used in the game for real.
- Is Ambient: The sound is assigned as an ambient sounds. I don't know if this must be checked for the game to know it's an ambient sound, or if you just have to place your ambient sounds in the right slots.

4. Volume
As explained earlier, this does NOT control how loud the game will physically play in the game. Rather, it controls the volume as if inside the game. In other words, the louder your sound is, the farther it can be heard in the map (in terms of number of polygons). I do not know the exact polygon counts for each setting. (Volume 3 is supposedly a "Louder" setting, but has only been seen used in the ZPC sound file so far - and has never been fully tested.)

5. Chance:
From what I've seen in the Marathon 2 source code, this value determines how often the sound is played when the conditions for hearing it are fulfilled. For example, in the original Infinity sounds file, most Human sounds have chance values ranging around 50%. This means that whenever a Bob is supposed to say something, there's only a 50% chance it will actually talk; otherwise, no sound is played. (This hasn't been verified.)

6. Low pitch and High pitch:
From what I've seen in the Marathon 2 source code, this determines the pitch of the sound when it is played. The pitch seems to be centered around 1.000, which plays the sound at its normal pitch. If both of these values are 0, the sound is played with a pitch of 1.000. If there's a value for the low pitch but no value for the high pitch, then the low pitch is used as the pitch value to play the sound. If both of these have a value, a pitch value is apparently chosen at random in-between these two boundaries and used to play the sound. (All of this hasn't been verified.)

7. Class ID and number
The ID is a unique number which is used by the Marathon engine to reference the class and its sounds. see the top of the document for more info on this parameter. When you add sounds in unused slots, make sure that their class IDs are set to valid numebrs which are unique. Similarly, set the class ID to -1 if you delete all sounds from a sound file. (Please note that currently, Wail performs NO CHECKING on the validity of a class ID - it doesn't even check do range checking like SE did. please be careful when editing class IDs.)

Classes are also numbered from the start of the file, starting at 0. This field shows the class number of the currently selected class.

8. Remap 8-bit:
This is a new feature in Wail. It was used in Anvil (although it didn't show up anywhere). The point is this: in the sound file, it is possible for 16-bit sound slots to simply point to the existing 8-bit sounds instead of having separate sounds. This allows some of the classes to have two versions of their sounds (8-bit and 16-bit versions) while other classes can only have 8-bit versions and then remap those in the 16-bit slots. This is useful, because using the 16-bit prefs in Marathon will crash if a class doesn't have 8-bit sounds (the engine won't remap on the fly). Checking this box will make the class remap its 8-bit sounds in the 16-bit slots. Please note that this will cause ALL existing 16-bit sounds to be deleted as they can no longer be used!


Working with sounds

As with SE, you can use Wail to move sounds around and play with them. You can cut or copy them, then paste them elsewhere. You can delete them either by hitting the Backspace or Delete keys, or by choosing "Clear" from the Edit menu or "Delete Sounds" (Cmd-D) from the Sound menu.

You can play a sound by hitting the Enter or Return keys, by double-clicking on it in the sound list, or by choosing "Play Sound" (Cmd-T) from the Sound menu. Also, choosing "Loop Sound" (Cmd-Y) from the Sound menu will cause the sound to play over and over again in a loop. This is useful when you want to test Ambient sounds.

When a sound is playing, be it looping or not, hitting Cmd-. (period) will stop it.

You can also import and export sounds in two formats: System-7 sounds (like the sounds you can record in ResEdit or the Sounds control panel), or AIFF. Importing and Exporting in System-7 sound format both have keyboard equivalents: Cmd-I and Cmd-E, respectively.

Wail also supports drag-n-drop for sounds. You can drag sounds from one list to another, from one window to another, or to and from the desktop (with sound clippings). To drag a sound, select it, then click and hold the mouse button and you should be able to drag it around. Also, when you move a dragged item over a sound list that can accept sounds, it should highlight to show that it can receive the drag.


Working with classes

SE could not do much with the classes in a sound file, 'cept display them. In Wail, however, you can manage the sound classes in a sound file just like you can manage the sounds.

It's possible to add classes to a file by choosing either "Add Class" or "Add Classes" in the Class menu. If you choose the latter, you will be asked to enter the number of classes to add. All classes created will have a class ID of -1, no flags, soft volume - just like Marathon's unused classes.

It's also possible to remove a class (the current one) by choosing "Remove Class" in the Class menu.

One cool feature, new in Wail also, is the ability to search for a class by its ID, name, or number. Just select "Find Class by ID", "Find Class by Name" or "Find Class by Number", enter the appropriate info and let Wail select it for you (if it exists). For name searches, there are options to ignore case and look for an exact match (if "Exact Match" is not selected, a partial name search is performed).

One word of warning: the Marathon engine won't accept files with a number of classes different from what it expects. By default, it expects to find 215 classes in the file (for Marathon ), or 203 classes (for Marathon 2). In order to have a different number of classes, you need to hack the engine. Fux! can help, but you'd better know what you're doing. In general, changing the number of classes is not for the faint of heart.


Saving your work

When you're done editing your sound file, choosing "Save" from the File menu will save its new content to disk, replacing the old content. You can also elect to "Save As" under a new name. If you try to close the window without saving, Wail will ask you to confirm.

If you have done some bad things and regret them, you can always choose "Revert" from the File menu to re-load the file as it was the last time you saved it. (When I say "bad things", I mean for the sound file. For other bad things, refer to your local priest and/or lawyer.)


Creating a shuttle

One thing that's currently missing in Wail is the ability to open shuttles within the editor. However, it's still possible to create them. You first have to create a sound file matching the content you'd have put in your shuttle. Then, choose "Make Shuttle From File" in the File menu and save your shuttle under a new name. Bingo, your shuttle is ready.

Running a shuttle asks you to choose a file as destination, and it will install all classes that are marked as used (i.e. with a class ID different from -1) into that destination file.

A cool feature has been added to the shuttle in version 2.1: now, classes with an ID of -2 will be installed as if they had an ID of -1. This allows you to flag empty classes so that they ARE included in the shuttle when creating one, and so that they install over any class, too. This basically allows you to replace used classes with empty ones.

If a shuttle finds that the destination file doesn't have the same number of classes as itself, it'll pop out a weird alert, asking if it must base itself on the file or the shuttle to decide how to install sounds. This is probably a mistake anyway, since you'll want to install the sounds in a file with the same number of classes.


Undo

Wail supports Undo. Cool, uh? :)

Seriously, Undo is partially implemented, meaning you can cancel your last modification easily if need be. It can Undo most sound-related commands like adding a sound, deleting a sound, changing the flags or volume, remapping the 8-bit sounds in 16-bit slots, editing the class ID, etc.

As of 2.5b1, even class-related actions (adding and removing sound classes) is undoable.


Managing Windows

Just like SE, Wail has a convenient Window menu that allows you to navigate through your open windows like a breeze. The first 10 windows to open will be assigned keyboard equivalents of Cmd-1 to Cmd-0. You can also select them directly in the menu.


Comparing files

Wail can compare sound files, just like SE. When a file is open, choose either "Compare With File..." or "Compare With Window..." to compare the current file with another (if you compare it to another window, it means you're comparing it with the content of another file already open in Wail).

The whole idea of comparing two files is to determine what you've changed between a sound file you modified and its original. For example, let's say you're working on a TC and you've heavily modified the sound file from the original game (say replace about half its content). Now you don't want to distribute that whole file since it contains Bungie sounds, and you'd like to know exactly which slots you've changed. No problem, just fire up the Compare thing, compare your file with the original M00 sound file, and you'll end up with a file that contains all the classes that were different from the original. All classes that were similar are now gone.

The whole idea is to build your modified file, save it, then Compare it with the original and then Make a shuttle containing the differences.


Preferences

Wail has quite a few preferences. They are divided into three categories at the moment. Here is a snapshot of the preferences window (which you can get by selecting "Preferences" from the Edit menu):




























The top control (1) allows you to select which preferences section you want to configure. The bottom box (2) shows the settings contained in the selected preferences section. (Here, the Editor section is shown.)

Editor section

Warn before deleting a sound: when you delete a sound, a warning will popup, asking you to confirm. (That warning also has a "don't show again" checkbox which can be used to turn that feature off.)

Warn before deleting 16-bit sounds when remapping: when you check the "Remap 8-bit" checkbox and the class contains 16-bit sounds, they must be deleted before the remapping takes effect. If this box is checked, a warning will popup, asking you to confirm. (That warning also has a "don't show again" checkbox which can be used to turn that feature off.)

Warn before deleting a class: when you delete a sound class, a warning will popup, asking you to confirm. (That warning also has a "don't show again" checkbox which can be used to turn that feature off.)

Compare 8-bit and 16-bit sounds...: this is a little tricky.

When Wail compares sound classes, it can either compare the class together (meaning it will treat its 8-bit and 16-bit sounds as being part of a single entity), or compare the 8-bit sounds and 16-bit sounds separately. If you compare them together, any difference in either 8-bit or 16-bit sounds will make the whole class different. If you compare them separately, 8-bit sounds could be different while 16-bit sounds would be the same. In this case, 16-bit sounds would be eliminated by the comparing process.

I'm still not quite sure if this is the ideal way of setting this up. Anyhow, the default is Separately, which resembles what SE did. You might find that comparing them together leads to a better result, however, if the sound files are set up in a similar way.

Class names section

This section has a single setting: the location of the Class Names file. By default, Wail should use the file located in its own folder. You can change that by clicking on the "Choose..." button and picking another file. Also, as the caption states, this file is loaded at startup time, so you'll need to restart Wail for changes to take effect.

Virtual Memory section

This section has a single setting also: the amount of protected RAM for the virtual memory system.

Essentially, Wail's scratch disk system will fill up the RAM when trying to load sound files, and when the RAM is full, it'll switch to disk-based allocation. However, Wail might need some free RAM to work properly (when cutting, copying and pasting sounds, or when playing them). By protecting a small amount of RAM, you guarantee that this amount will never by used when loading a sound file, thus always being available to keep temporary sounds in RAM.

The default setting is 1 meg. If you think you'll be manipulating sounds bigger than 1 meg, pump up that value. You'd better not set it below 1 meg, however, as Wail will probably need at least this much to live. But who knows.


Wrapping up...

Well, this pretty much concludes these little docs. I hope it helps you figure out the interface and main features of Wail. If you think something is missing or unclear, please write me at danov@videotron.ca to ask me about it. Maybe I can update it for a future version.